home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / dmedia / dm_jpeg.z / dm_jpeg
Encoding:
Text File  |  1998-10-20  |  17.4 KB  |  331 lines

  1.  
  2.  
  3.  
  4. ddddmmmmIIIICCCC((((3333ddddmmmm))))                                                            ddddmmmmIIIICCCC((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      dm_jpeg - JPEG compression programming with dmIC and dmBuffers
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ddddmmmm____iiiimmmmaaaaggggeeeeccccvvvvtttt....hhhh>>>>
  13.      #include <dmedia/dm_jpeg.h>
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      The JPEG compression standard (ISO/IEC 10918) operates with ddddmmmmIIIICCCC and
  17.      ddddmmmmBBBBuuuuffffffffeeeerrrrssss as described in this man page.  The ddddmmmmIIIICCCC man pages are generic
  18.      and contain no information about specific compression schemes.  This man
  19.      page describes details of ddddmmmmIIIICCCC specific to baseline (DCT-based, Huffman-
  20.      encoded) JPEG.
  21.  
  22.      NOTE: Some previous generation realtime JPEG products are not supported
  23.      via this interface.  Indy Cosmo and Indigo2 Cosmo2 are available only via
  24.      the Compression Library (CL).  See CCCCLLLLiiiinnnnttttrrrroooo and ccccllll____jjjjppppeeeegggg for more
  25.      information.
  26.  
  27. AAAAVVVVAAAAIIIILLLLAAAABBBBLLLLEEEE JJJJPPPPEEEEGGGG IIIIMMMMAAAAGGGGEEEE CCCCOOOONNNNVVVVEEEERRRRTTTTEEEERRRRSSSS
  28.      A variety of realtime JPEG hardware products operate under this
  29.      programming interface.  There is a basic common subset of JPEG supported
  30.      in all implementations.
  31.  
  32. FFFFIIIINNNNDDDDIIIINNNNGGGG AAAANNNNDDDD CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA JJJJPPPPEEEEGGGG CCCCOOOONNNNVVVVEEEERRRRTTTTEEEERRRR
  33.      This section describes how to use ddddmmmmIIIICCCC operations to find and create a
  34.      JPEG image converter for either encode (compression) or decode
  35.      (decompression) in realtime or non-realtime.  (Realtime generally refers
  36.      to a JPEG converter that operates at video rate -- NTSC, PAL, or 601).
  37.  
  38.      A JPEG image converter's DDDDMMMM____IIIICCCC____IIIIDDDD parameter -- from the DMparams list
  39.      returned by ddddmmmmIIIICCCCGGGGeeeettttDDDDeeeessssccccrrrriiiippppttttiiiioooonnnn -------- has the value ''''jjjjppppeeeegggg''''....
  40.  
  41.      The DDDDMMMM____IIIICCCC____SSSSPPPPEEEEEEEEDDDD parameter will have the value DDDDMMMM____IIIICCCC____SSSSPPPPEEEEEEEEDDDD____RRRREEEEAAAALLLLTTTTIIIIMMMMEEEE if the
  42.      converter is capable of video rate processing.  If the value is
  43.      DDDDMMMM____IIIICCCC____SSSSPPPPEEEEEEEEDDDD____NNNNOOOONNNNRRRREEEEAAAALLLLTTTTIIIIMMMMEEEE the converter is not capable of operating at
  44.      video rate.
  45.  
  46.      The DDDDMMMM____IIIICCCC____CCCCOOOODDDDEEEE____DDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNN parameter indicates if the converter compresses
  47.      or decompresses.  If the value is DDDDMMMM____IIIICCCC____CCCCOOOODDDDEEEE____DDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNN____DDDDEEEECCCCOOOODDDDEEEE then the
  48.      input to the converter is JPEG and the output is pixel data.  If the
  49.      value is DDDDMMMM____IIIICCCC____CCCCOOOODDDDEEEE____DDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNN____EEEENNNNCCCCOOOODDDDEEEE then the input to the converter is
  50.      pixel data and the output is JPEG.
  51.  
  52.      The following code fragment shows how to find a realtime JPEG decoder and
  53.      create a context for operating on it:
  54.  
  55.      DMimageconverter ic;
  56.      DMparams *p;
  57.      int n = dmICGetNum();
  58.      while (n--) {
  59.           dmParamsCreate(&p);
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ddddmmmmIIIICCCC((((3333ddddmmmm))))                                                            ddddmmmmIIIICCCC((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.          if (dmICGetDescription(n, p) == DM_SUCCESS
  75.                dmParamsGetInt(p, DM_IC_ID) == 'jpeg' &&
  76.                dmParamsGetEnum(p, DM_IC_SPEED) == DM_IC_SPEED_REALTIME &&
  77.                dmParamsGetEnum(p, DM_IC_CODE_DIRECTION) ==
  78.                                    DM_IC_CODE_DIRECTION_DECODE) {
  79.                dmParamsDestroy(p);
  80.                break;
  81.           }
  82.           dmParamsDestroy(p);
  83.      }
  84.      dmICCreate(n, &ic);
  85.  
  86.      The number of simultanously active realtime JPEG converters system-wide
  87.      may exceed the capabilities of the underlying hardware.  That is, one or
  88.      more programs may create one or more JPEG converter contexts and if too
  89.      many are simultaneously compressing or decompressing JPEG data the result
  90.      may be less than realtime for one or more contexts.
  91.  
  92. JJJJPPPPEEEEGGGG CCCCOOOONNNNVVVVEEEERRRRTTTTEEEERRRR CCCCOOOONNNNTTTTRRRROOOOLLLL
  93.      These sections describe how generic and JPEG-specific parameters are used
  94.      to control a JPEG converter.  In general each parameter value should be
  95.      considered undefined until set explicitly by the program.
  96.  
  97.      The input image format, the output image format and the conversion
  98.      operation are controlled using ddddmmmmIIIICCCCSSSSeeeettttSSSSrrrrccccPPPPaaaarrrraaaammmmssss,,,, ddddmmmmIIIICCCCSSSSeeeettttDDDDssssttttPPPPaaaarrrraaaammmmssss,,,, and,
  99.      ddddmmmmIIIICCCCSSSSeeeettttCCCCoooonnnnvvvvPPPPaaaarrrraaaammmmssss repectively.
  100.  
  101.      The following discussion will use the terms ssssoooouuuurrrrcccceeee and ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnn to
  102.      refer to the image format of the converter input and output,
  103.      respectively.  The terms ccccoooommmmpppprrrreeeesssssssseeeedddd ssssiiiiddddeeee and uuuunnnnccccoooommmmpppprrrreeeesssssssseeeedddd ssssiiiiddddeeee will
  104.      generally refer to parameters of the source and destination respectively
  105.      if the converter is a JPEG decoder and vice versa if the converter is a
  106.      JPEG encoder.
  107.  
  108. JJJJPPPPEEEEGGGG SSSSOOOOUUUURRRRCCCCEEEE AAAANNNNDDDD DDDDEEEESSSSTTTTIIIINNNNAAAATTTTIIIIOOOONNNN IIIIMMMMAAAAGGGGEEEE FFFFOOOORRRRMMMMAAAATTTT
  109.      The image orientation, width, height, and pixel format must be set on
  110.      both the source and destination side of the converter.  Use of
  111.      ddddmmmmSSSSeeeettttIIIImmmmaaaaggggeeeeDDDDeeeeffffaaaauuuullllttttssss is recommended to set the DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____WWWWIIIIDDDDTTTTHHHH,,,,
  112.      DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____HHHHEEEEIIIIGGGGHHHHTTTT,,,, and DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____PPPPAAAACCCCKKKKIIIINNNNGGGG parameters.  The width and height
  113.      on the compressed side must match the native size of the JPEG encoded
  114.      data.  (A note on obtaining width and height for image data stored in a
  115.      movie file appears later in this man page.)
  116.  
  117.      The DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____CCCCOOOOMMMMPPPPRRRREEEESSSSSSSSIIIIOOOONNNN parameter must be set to DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____JJJJPPPPEEEEGGGG on the
  118.      source or destination side as appropriate for the conversion direction.
  119.  
  120.      All JPEG image converters support the DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____PPPPAAAACCCCKKKKIIIINNNNGGGG____CCCCbbbbYYYYCCCCrrrrYYYY on the
  121.      compressed side.  This is the same as the Video Library pixel packing for
  122.      4:2:2 video VVVVLLLL____PPPPAAAACCCCKKKKIIIINNNNGGGG____YYYYVVVVYYYYUUUU____444422222222____8888,,,, and is the same as the OpenGL
  123.      GGGGLLLL____YYYYCCCCRRRRCCCCBBBB____444422222222____SSSSGGGGIIIIXXXX format for use with ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss on some machines (O2,
  124.      for example).
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ddddmmmmIIIICCCC((((3333ddddmmmm))))                                                            ddddmmmmIIIICCCC((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      The following code fragment configures the source and destination of the
  141.      realtime decoder context created in the previous example.  Error
  142.      processing is left off for clarity:
  143.  
  144.      DMparams *p;
  145.      int wid, ht;
  146.      size_t imagebytes;
  147.  
  148.      dmParamsCreate(&p);
  149.      dmSetImageDefaults(p, wid, ht, DM_IMAGE_PACKING_CbYCrY);
  150.      dmParamsSetEnum(p, DM_IMAGE_ORIENTATION, DM_IMAGE_TOP_TO_BOTTOM);
  151.      dmParamsSetString(p, DM_IMAGE_COMPRESSION, DM_IMAGE_JPEG);
  152.      dmICSetSrcParams(ic, p);
  153.      imagebytes = dmImageFrameSize(p);
  154.  
  155.      dmParamsSetString(p, DM_IMAGE_COMPRESSION, DM_IMAGE_UNCOMPRESSED);
  156.      dmICSetDstParams(ic, p);
  157.      dmParamsDestroy(p);
  158.  
  159.      In the above code note that the DMparams list pppp is recycled since only
  160.      one parameter value is different between the source and destination
  161.      formats.  This is safe since ddddmmmmIIIICCCC saves away the values of the paramters
  162.      of interest before returning from any call accepting a DMparams as an
  163.      argument.  Also note the use of ddddmmmmIIIImmmmaaaaggggeeeeFFFFrrrraaaammmmeeeeSSSSiiiizzzzeeee to impute the size (in
  164.      bytes) of an image described by the given parameters.  The orientation in
  165.      this example is DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____TTTTOOOOPPPP____TTTTOOOO____BBBBOOOOTTTTTTTTOOOOMMMM which is the proper orientation of
  166.      video imagery and is the value required for DM_IMAGE_ORIENTATION to
  167.      ensure realtime processing.
  168.  
  169.      WARNING: A realtime JPEG converter may not necessarily operate in
  170.      realtime if one or more of the image parameters (other than
  171.      DM_IMAGE_COMPRESSION) is different between source and destination.  That
  172.      is, the implied conversion (from one width and height to a different if
  173.      those paramters are different) may take place in software.
  174.  
  175.      All realtime JPEG converters will operate at video rate if the compressed
  176.      side is 4:2:2 (DM_IMAGE_PACKING_CbYCrY) and the uncompressed side is
  177.      either 4:2:2 YCrCb or RGB (DM_IMAGE_PACKING_XBGR).  The conversion
  178.      algorithm used for RGB assumes strict Recommendation 601 values for the
  179.      YCrCb color model (blackest black is Y=16, 1-15 are clamped to 16, peak Y
  180.      is 240, 241-255 clamped to 240, etc).  NOTE: This is a slighty different
  181.      color model than that used in JFIF images.
  182.  
  183. JJJJPPPPEEEEGGGG CCCCOOOONNNNVVVVEEEERRRRSSSSIIIIOOOONNNN CCCCOOOONNNNTTTTRRRROOOOLLLLSSSS
  184.      Aside from the rudimentary image conversion controls on width, height,
  185.      pixel packing, orientation and so forth there are controls specific to
  186.      the JPEG encode process typically to control the image quality or the
  187.      compression ratio or bitrate.  This section describes parameters for use
  188.      with ddddmmmmIIIICCCCSSSSeeeettttCCCCoooonnnnvvvvPPPPaaaarrrraaaammmmssss....
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ddddmmmmIIIICCCC((((3333ddddmmmm))))                                                            ddddmmmmIIIICCCC((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206.      The JPEG quality factor (a scaling of the quantization tables) is
  207.      controlled using the DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____QQQQUUUUAAAALLLLIIIITTTTYYYY____SSSSPPPPAAAATTTTIIIIAAAALLLL parameter.  The parameter
  208.      value ranges from 0.0 (lowest quality and most compression) to 1.0
  209.      (highest quality and least compression).  Setting this control overrides
  210.      (erases) the converters internal setting for bitrate (if such had been
  211.      previously set by the program).
  212.  
  213.      The compression ratio is controlled using DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____BBBBIIIITTTTRRRRAAAATTTTEEEE.... Use of this
  214.      control erases the converter's internal setting of quality (if such had
  215.      been previously set by the program).  The JPEG encoder destination
  216.      parameters for DM_IMAGE_RATE (frames per second) and DM_IMAGE_INTERLACING
  217.      (essentially indicating fields or frames) must be set explicitly by the
  218.      program to engage the rate control mechanism of the encoder.  The actual
  219.      data rate acheived is "best effort" and may vary from image to image, but
  220.      the average will tend towards the desired value.  All realtime encoders
  221.      are capable of acheiving an average rate in the range of 2 to 30
  222.      megabits/second.  Some realtime encoders may be capable of higher rates.
  223.      Note that some _d_e_c_o_d_e_r_s have a maximum bitrate that is different than its
  224.      companion encoder.
  225.  
  226.      It is recommended that the program set either the quality or bitrate
  227.      explicitly. If both DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____BBBBIIIITTTTRRRRAAAATTTTEEEE and DDDDMMMM____IIIIMMMMAAAAGGGGEEEE____QQQQUUUUAAAALLLLIIIITTTTYYYY____SSSSPPPPAAAATTTTIIIIAAAALLLL
  228.      parameters are set then bitrate setting prevails and the quality setting
  229.      is used as the initial condition for the compressed image size.
  230.  
  231. JJJJPPPPEEEEGGGG,,,, QQQQUUUUIIIICCCCKKKKTTTTIIIIMMMMEEEE,,,, AAAANNNNDDDD TTTTHHHHEEEE MMMMOOOOVVVVIIIIEEEE LLLLIIIIBBBBRRRRAAAARRRRYYYY
  232.      Here are some notes on how to access the Quicktime Motion JPEG Type-A
  233.      file format using the Movie File Library specifically to transfer data
  234.      between a JPEG image converter and the Movie File using ddddmmmmBBBBuuuuffffffffeeeerrrrssss....
  235.  
  236.      When using JPEG with the Movie File Library the width and height of the
  237.      images in a track may be obtained using mmmmvvvvGGGGeeeettttIIIImmmmaaaaggggeeeeWWWWiiiiddddtttthhhh and
  238.      mmmmvvvvGGGGeeeettttIIIImmmmaaaaggggeeeeHHHHeeeeiiiigggghhhhtttt....
  239.  
  240.      The height of an image in the track is that of a full frame whether the
  241.      each image is stored as a field pair or a frame.  If the track data is
  242.      interlaced then the appropriate value to use for the DM_IMAGE_HEIGHT
  243.      parameter with the image converter is half that of the value returned
  244.      from the movie file.  That is, the Movie Library operates in terms of
  245.      full frames in contrast to ddddmmmmIIIICCCC and JPEG which operates only in terms of
  246.      images.  A ddddmmmmIIIICCCC JPEG converter must therefore be informed of the exact
  247.      dimensions of the image.  It's the program's responsibility to know
  248.      whether each image represents a field or a frame and to know the
  249.      dimensions in either case.
  250.  
  251.      The mmmmvvvvIIIInnnnsssseeeerrrrttttTTTTrrrraaaacccckkkkDDDDaaaattttaaaaFFFFiiiieeeellllddddssss call is used when creating a Quicktime Motion
  252.      JPEG Type-A file of pairs of fields of JPEG encoded video.  And, the
  253.      mmmmvvvvGGGGeeeettttTTTTrrrraaaacccckkkkDDDDaaaattttaaaaFFFFiiiieeeellllddddIIIInnnnffffoooo and mmmmvvvvRRRReeeeaaaaddddTTTTrrrraaaacccckkkkDDDDaaaattttaaaaFFFFiiiieeeellllddddssss calls are used to read
  254.      pairs of fields from a Quicktime file.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. ddddmmmmIIIICCCC((((3333ddddmmmm))))                                                            ddddmmmmIIIICCCC((((3333ddddmmmm))))
  269.  
  270.  
  271.  
  272. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  273.      dmIC(4), dmBuffer(4), mvIntro(3dm), VLintro(3dm).
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.